Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceltrack/3.0/subscription/webhook/
Production:
https://api.nzpost.co.nz/parceltrack/3.0/subscription/webhook/
Resource Description
Creates a subscription with provided tracking reference or TPID and webhook url.
| Attribute | Detail |
|---|
| Response Format | JSON |
| Requires Authentication | Yes |
| Rate Limited | 15 calls per second across all merchants using the API. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Request Parameters
| Field Name | Description | Mand | Example |
|---|
| account_number | TPID for merchant | Yes | 91327067 |
| tracking_reference | Unique identifier for the parcel | No | JS21317298172NZ |
| notification_endpoint | The webhook URL to receive the notifications | Yes | http://www.acme.co.nz/webhooks/tracking |
Sample Request - Subscription object is tracking reference
{
"tracking_reference":"JS21317298172NZ",
"notification_endpoint":"http://www.acme.co.nz/webhooks/tracking"
}
Sample Request - Subscription object is TPID
{
"account_number":"91327067",
"notification_endpoint":"http://www.acme.co.nz/webhooks/tracking"
}
Business Rules
The following business rules are applied on each /subscription/webhook request:
| Name | Description |
|---|
| BR001 | A subscription must contain either a tracking reference or a TPID |
| BR002 | ParcelTrack subscription information can only be delivered via webhook |
Response Parameters
The following lists the fields in the response message.
| Field Name | Description | Mand | Example |
|---|
| success | Returns true if request is successful else false | Yes | True |
| message_id | A unique identifier for the API Call | Yes | 0d41ffa0-0976-11e5-8fa8-02850e3bb9fb |
| subscription_guid | A unique identifier for the subscription | Yes | 32ffd9bd-8ea5-4167-85d8-a20d4a5e7a31 |
| errors | If the subscription creation is unsuccessful, an error code and message is provided | Yes if API call is unsuccessful | See section Error Object Parameters |
Error Response Elements
| Field Name | Description | Mand | Example |
|---|
| success | Returns if request is successful | Yes | True |
| errors | Error object with error details | Y if success =false | See Error Object Parameters below |
| message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
| Field Name | Description | Example |
|---|
| code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
| message | Description of error code | Invalid Parameter(s) |
| details | Description of specific error | The parameter tracking_reference cannot be empty |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
| Code | Message |
|---|
| 200 | Success |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 409 | Invalid request |
| 500 | System unavailable |
Error Codes
| Code | Message |
|---|
| 200001 | Partial results returned, not all system(s) have responded |
| 200002 | All sources responded, data may be incomplete |
| 400001 | Parameter(s) missing |
| 400002 | Invalid parameter(s) |
| 400003 | Non mutually exclusive parameters detected |
| 401001 | Unauthorised access, please contact administrator |
| 500001 | General Exception |
| 500002 | System(s) offline |
Sample Response
Sample: Success
{
"success": true,
"subscription_guid": "32ffd9bd-8ea5-4167-85d8-a20d4a5e7a31",
"message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}
Sample: Failure
{
"success": false,
"errors": [ {
"code": "400002",
"message": "Invalid parameter(s)",
"details": "The parameter tracking_reference cannot be empty"
}],
"message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}